Please visit www.soundspectrum.com to learn more about the standard versoin of WhiteCap and all of the options available for customizing WhiteCap.

      You can customize WhiteCap by editing its preferences file, editing its "boot" file, or by writing your own scripts. The preferences file, the boot file, and all script files are plain-text files and end with ".txt". If you edit these files, then you must resave them as plain-text. Otherwise, WhiteCap could crash while trying processing them. In Windows, Notepad is an effective and convenient plain-text editor. Whatever text editor you do use, it's recommended that you disable line wrapping for readability and in order to prevent mistaking wrapped lines for new lines.

      In general, you should avoid editing the pref file and boot file when possible. You can instead change commonly altered settings via key commands (assuming your media player supports keystrokes for plugins, press 'H' to display an on-screen list of key commands). An example of when you would edit the prefs file would be if you media player didn't support keystrokes, or if you wanted to edit a setting not accessible via key commands. Finally, if you have the option to edit either the pref file or the boot file in order to achieve your goal, it's always preferable to edit the prefs file rather than the boot file. A mistake in the prefs file can always be corrected by deleting the prefs file (and a factory prefs file will be written in its place), but a mistake in the boot file can only be corrected by replacing it with the original boot file (ie. reinstallation).

The Boot File

The "boot" file is read-in and executed when WhiteCap first starts-up (to find it, you can search for "boot.txt"). This file is a sequence of commands that initialize (or "bootstraps") WhiteCap and prepares it for normal operation (the term "boot" originates from the phrase "to pull up from the bootstraps", from the earliest days of computers, reflecting that computers start with absolutely nothing when they're turned on). Unlike the preferences file, the boot file is never altered or rewritten by WhiteCap—it's only read-in (and executed) when WhiteCap first starts-up. The boot file is like a boot disk for your computer—without it, WhiteCap cannot operate normally. It's recommended that you study the boot file because it contains detailed comments and serves as a good example of the WhiteCap script/command language.

The Preferences File

The WhiteCap preferences file is a "config" file, meaning it's a plain-text file containing a simple list of values (in no particular order). Its file format is intended to be learned extremely quickly and edited easily using any text editor—the format is described in the config programming section. The purpose of the prefs file is to allow various user variables (ex, window position, full screen resolution, visual reactivity settings) to persist from each time WhiteCap is run to the next. Since WhiteCap only writes/updates the prefs file when it exits, you will have to run and exit WhiteCap at least once before you'll be able find a WhiteCap prefs file—search for "WhiteCap Prefs" on your system to see where WhiteCap stores its prefs file (it's location varies depending on your media player, OS, and user permissions). If you edit the prefs file while WhiteCap is running, your changes will be overwritten when WhiteCap exits (so you should save your changes when WhiteCap is not running). Finally, if WhiteCap behaves strangely after you edit the prefs file, it's likely you inadvertently inserted an error. You can simply delete the prefs file (when WhiteCap isn't running) and a new "factory" prefs file will be created the next time WhiteCap runs. The following is a list of all the parameters found in the WhiteCap prefs file:

G-Force and WhiteCap Common Prefs
FSrt	PREF_FFT_BIN_START	When G-Force is operating as a plugin for a media player, the media player repeatedly passes an array of values corresponding to a fft (fourier transform) of the "current" audio. For cosmetic purposes, this FSrt defines how many values or "bins" of this array to throw away from the low-frequency side (the first several values are usually erratic since the lowest frequencies become increasingly more difficult to analyze). Hence, increasing FSrt will cause the frequency window of fft(0..1) to shift to the right (towards the high frequency end of the fft).      Note: this parameter is not used in stand-alone or engine/export mode because G-Force uses its own built-in fourier transformer and uses the parameters set by SetFFTParams() (see the boot.txt file).
FRge	PREF_FFT_BIN_RANGE	When G-Force is operating as a plugin for a media player, the media player repeatedly passes an array of values corresponding to a fft (fourier transform) of the "current" audio. For cosmetic purposes multiple adjacent elements (or "bins") are averaged into one G-Force bin. This parameter specifies just how many media player fft bins are averaged per G-Force bin.     Therefore, this affects how wide of a frequency band the elements of fft(0..1) span. As FRge increases, the frequency band fft(0..1) increases. For example, if FRge is large then fft(0) may be the magnitude of the frequencies from 100 to 500 Hz, while if FRge is smaller then fft(0) may be the magnitude of the frequencies from 100 to 200 Hz.      Note: this parameter is not used in stand-alone or engine/export mode because G-Force uses its own built-in fourier transformer and uses the parameters set by SetFFTParams() (see the boot.txt file).
FFde	PREF_FFT_FADE_AWAY	The higher this value, the slower each fft element (or "bin") will fall/drift back to zero after it's been excited. Likewise, as this number approaches zero, the faster fft bins will fall to zero. Slower music tends to look better if this value is 30-50% higher than the factory value because frequency "tonals" will accumulate more and will form more defined peaks.
FSmo	PREF_FFT_SMOOTH	As this value increases, the smoothing of fft(0..1) increases proportionally (ie, peaks and valleys will be less jagged). Approximately doubling/halving this number will double/half the amount of smoothing.
FNum	PREF_FFT_NUM_BINS	This defines how many values/elements are in fft(0..1). As FNum increases, the frequency spectrum will be divided up into more "bins" (a "bin" is defined as the average value of a small sub-section of a frequency spectrum--just like how a bin or pail collects a footprint of rain and never a point). In a config file, you can access 'FNum' by using NUM_FFT_BINS. See the documentation in the example configs, especially the documentation of the Stps parameter in "Rotating Corridor".
FMap	PREF_FFT_MAP_FCN	This is a function that maps the input/raw fft array (from either a media player or from the built-in fourier transformer while in stand-alone or engine/export mode) to the array that is accessed by fft(0..1). An "array" here simply means a sequence of values. The purpose of this function is to provide an arbitrary means to change the fft spectrum ultimately seen by the user such that it's as visually appealing and responsive as possible. The fft spectrum that comes from media players or G-Force's built-in fourier transformer is "raw", meaning that it would be very visually unappealing if was used directly.     There are two values accessible from inside the function, w and x. The value w can be thought of a vector that goes from 0 to 1, the 0 corresponding to the low-frequency side of the fft array, 1 corresponding to the high-frequency side of the fft array. The value x can be thought of the raw/input fft array. For example, a proportional mapping of the raw fft array with a 100% increasing to 200% weighting on the higher frequencies would be:         ".1 * x * ( w + 1 )"
PSmo	PREF_PCM_SMOOTH	As this value increases, the more mag(0..1) is smoothed (ie, peaks and valleys will be less jagged). Approximately doubling/halving this number will double/half the amount of smoothing.
PNum	PREF_PCM_NUM_BINS	Similar to FNum, this parameter specifies how many elements are in each sound sample (that is, how many elements make up mag(0..1)). PCM stands for "pulse code modulation" which just means a sequence of amplitude values that correspond to the position of a recording membrane. A "sample" is slang for a sequence of amplitude values that form a short clip of audio—in other words a "sample" is slang for a recorded audio segment. 'PNum' defines how many steps is in mag(0..1). In a config file, you can access PNum with the global variable NUM_SAMPLE_BINS.
PScl	PREF_PCM_SCALE	This sets the scale factor to the PCM level (ie. the oscilloscope-looking output of WaveShapes). You would adjust the PCM scale if the PCM level (and only the PCM level) was too large or too small, and adjusting this value will have no effect on the FFT level whatsoever (ie, PScl will scale mag() and only mag()). Normally, you should scale the FFT level in tandem with the PCM level (by changing the response scale (below), not the PCM scale).
RScl	PREF_RESPONSE_SCALE	The "response scale" will scale the *output* of the FFT map function (ie, it scales the output of PREF_FFT_MAP_FCN) as well as the PCM input. An analogy would be a "line" source connected to a preamp, going to an equalizer, going to another amplifier. The preamp scale turns up/down the pre-amp, PREF_FFT_MAP_FCN specifies the equalizer's settings, and the response scale turns up/down the second amp. In general, you'll only want to adjust the preamp scale if line-in level is abnormally high or low (ex, you have a poor mic that only gives your a fraction of the signal). Most of the time, you'll want to adjust the response scale to suit your personal visual tastes. For the PCM data (ie. the oscilloscope-looking output accessed by mag(0..1)), since there is no FFT mapping function (in the analogy, no equalizer), the preamp and the response scale are interchangeable (because having no FFT remapper makes them communitive).     In summary:        - mag(0..1) = RScl * SScl * PScl * mag_raw(0..1)        - fft(0..1) = RScl * PREF_FFT_MAP_FCN( w = 0..1, x = SScl * fft_raw(0..1) )
SScl	PREF_PREAMP_SCALE	The "preamp scale" will scale the *input* of the FFT map function (ie, it scales the raw FFT input before it's transformed by PREF_FFT_MAP_FCN) as well as the PCM input—see above. In general, you should only adjust the preamp scale if line-in level is abnormally high or low (ex, you have a poor mic that only gives your a fraction of the signal).
FS_M	PREF_FULLSCREEN_DEVICE	This specifies the display device that G-Force will attempt to use for full screen mode. The value is such that the main/primary device is 0, the next is 1, the next is 2, and so on. If this value is -1 (ie, SS_HOST_DISPLAY_DEVICE), then the display device that G-Force will attempt to use for full screen mode will be whatever the display device currently hosting the G-Force window. Note: this is not available for all media players (because most media players don't allow a plugin to request a specific display device for full scree mode).
FS_D	PREF_FULLSCREEN_DEPTH	This is the color depth mode G-Force will use when it attempts to enter full screen mode (it can only be 8, 16, or 32). In G-Force, 8 and 32 bit mode will produce the same color-quality frames, but 32 will be slower because 4 times the pixel data is moved around (ie, 1 byte per pixel vs. 4 bytes per pixel). The only time you should use 32 for FS_D in G-Force is if your OS improperly supports 8 bit mode (which, sadly, is common). To discover which fullscreen mode is best for your setup, try comparing the average frame rate under different fullscreen depth modes in order. Pressing SHIFT M will step through the available full screen depth modes. Note: because G-Force tries to maintain a specified frame rate (see the 'FPS' pref), to conduct a frame rate comparison you should set the 'FPS' pref to a value G-Force won't be able to achieve (ex. 100).
FS_X FS_Y	PREF_FULLSCREEN_X PREF_FULLSCREEN_Y	This determines the display resolution mode G-Force will use when it attempts to enter fullscreen mode. You can step through the available the fullscreen modes by repeatedly pressing the "Switch full screen mode" key (the 'M' key). Because G-Force's frame rate is proportional to how many pixels it must draw, frame rate is low as the total number of pixels increases (ie, as the product of these two values increases). You can use the MaxX and MaxY prefs to restrict G-Force's active frame size, allowing you to increase frame rate for any particular fullscreen resolution.
MaxX MaxY	PREF_MAX_SIZE_X PREF_MAX_SIZE_Y	These set a limit on the pixel dimensions of the "active" output frame size. For example, by restricting MaxY to, say, 600, you will see G-Force "letterbox" once its vertical height exceeds 600. Or, suppose 1024x768 fullscreen mode causes unacceptably low frame rates on your setup. You could set MaxY to, say, 500, and you will have higher frame rates in that same fullscreen mode (because G-Force has fewer pixels to render).
PDbl	PREF_PIXEL_DOUBLING	If non-zero, G-Force will internally render frames half the size of the current output frame size and double them when they're drawn to the screen. The end result is that G-Force only has to render one quarter of the pixels (decreasing CPU load), but the graphic output will look granular or "pixelated". The performance increase from using pixel doubling will vary based on your setup's OS and graphics hardware.
MBlt	PREF_FORCE_MULTIBLT	When the output device is in 16 or 32 bit color mode and an overlay is present (ex, album cover art or floating white text), the overlay must ultimately be combined with each G-Force [8 bit] output frame (note that all overlays are 32 bit color). G-Force has two options: (a) copy the G-Force frame to the 16/32 bit OS frame buffer and then copy (or "blt") the overlay over it, or (b) copy the G-Force frame into a temp 16/32 bit buffer, blt the overlay over it, and then blt the temp buffer to the OS frame buffer. Option (a) is obviously preferable, but unless the OS frame buffer is triple buffered, frame "tearing" or flickering can occur (where only part of the frame appears). By default, if G-Force detects an environment such that option (a) will cause frame tearing or flickering, then G-Force will employ option (b) instead (typically resulting in a noticeable performance penalty).
NoBo	PREF_BORDERLESS_WINDOW	If non-zero, G-Force will try to make its window borderless. Note: this is not supported for all media players and/or OSes.
FWin	PREF_FLOATING_WINDOW	If non-zero, G-Force will try to "float" its window above other windows. Note: this is not supported for all media players and/or OSes.
ArtX ArtY	PREF_MAX_COVER_ART_X PREF_MAX_COVER_ART_Y	If album cover art is available, these parameters limit the cover art's image dimensions to a specific pixel size. If one (or both) of the cover art's dimensions exceeds these limits, the cover art is scaled down such that the new size is inside these limits.
FPS	PREF_DESIRED_FRAME_RATE	G-Force will attempt to maintain a frame rate that matches the value specified in this pref. If G-Force has a frame rate below what you specify, it's because (a) your system isn't fast enough to achieve the desired frame rate for the current frame dimensions, or (b) the host media player is electing not to have G-Force draw as often as possible. At this point, only decreasing the frame size, exiting other applications, or switching media players can increase frame rate.     Note that some media players only call a visual plugin a maximum number of times per second (and nothing can be done to change that other than abandon that media player). Also note that it takes a few seconds for G-Force to stabilize on the desired frame rate when a step-change in CPU load occurs (ex, window size change, multiple overlays added at once).
LBst	PREF_LINE_BOOST	This value of this parameter is added to the line thickness of all drawn lines. Higher resolution users typically use 1 or 2 so that lines are more visible. On G-Force, note that increasing line thickness can cause more frequent color saturation (depending on the current FlowField), causing the entire screen to be flooded with an excess of foreground color.
TTxt	PREF_TRACK_TEXT_AUTO	If this value is non-zero, track text (and album art, if available) will be automatically displayed when the current song changes. If this value is zero, track text and album cover art will never appear automatically.
TDur	PREF_TRACK_TEXT_DURATION	This is the number of seconds track text (and album cover art, if available) will remain visible after it appears. By default, track text (and album cover art) will appear when a new track begins or when 'T' is pressed.
TFnt	PREF_TEXT_FONT	This specifies the default font name used when track information text or Sprite text is drawn. Note that text Sprites can override this by specifying their own TFnt (in their config file)—this allows you to make specific text sprites appear in a specifc way.
TSze	PREF_TEXT_SIZE	This specifies the default text size used when track information text or Sprite text is drawn. Note that text Sprites can override this by specifying their own TSze (in their config file)—this allows you to make specific text sprites appear in a specifc way.
A_in	PREF_AUDIO_INPUT_SOURCE	This specifies the audio input source to be visualized. A value of zero represents the default audio input device/source. This pref is only used when G-Force is running in stand-alone mode.
UpCk	PREF_CHECK_FOR_UPDATES	This specifies how often, in days, G-Force will anonymously check soundspectrum.com for updates when it starts up. If a newer version of G-Force exists (than the version currently running), you will be notified that a new version is available. If you wish to disable this feature, set this pref to 0.
Vers	PREF_PREFS_VERSION	This stores the version of the prefs file and is how G-Force can identify an out-of-date prefs file (if this value is below the "compatible" version number, G-Force will use the "factory" pref values specified in the boot file). You will never normally need to edit this value (and using an invalid or out-of-date prefs file with the "current" G-Force version number could cause G-Force to crash or operate improperly).
wTop wLft wBot wRgt	N/A	This stores the position of the G-Force window in globsal screen coordinates. Note that when G-Force runs under certain media players, these parameters aren't used because the host media player manages the rectangle size and position, not G-Force.